feat: typed Google Search parameters and responses (fixes #33)#37
feat: typed Google Search parameters and responses (fixes #33)#37kenrogers wants to merge 1 commit intoserpapi:masterfrom
Conversation
Replace Record<string, any> with GoogleSearchParameters and GoogleSearchResponse for the Google engine. Adds a typed overload to getJson() so users get autocomplete and validation when passing engine: "google". Generic types preserved for backwards compatibility. Pattern is extensible to other engines (Bing, YouTube, etc.) by adding files under src/engines/. Fixes serpapi#33
There was a problem hiding this comment.
Pull request overview
Introduces engine-specific TypeScript typings for SerpApi’s Google Search, and wires those types into the public API so Google searches can have autocompleted parameters and typed JSON responses.
Changes:
- Added Google Search engine parameter/response interfaces under
src/engines/google.tsand re-exported them viasrc/types.ts. - Added a typed overload for
getJson()when called withGoogleSearchParameters. - Added a new test file intended to validate compile-time behavior of the new types.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
src/engines/google.ts |
Adds Google Search request/response type definitions. |
src/types.ts |
Re-exports Google engine-specific types from the new engine module. |
src/serpapi.ts |
Adds getJson() overload to provide typed Google Search responses. |
mod.ts |
Re-exports new Google-related types from the package entrypoint. |
tests/types_test.ts |
Adds tests intended to validate engine-specific typing behavior. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| GoogleSearchResponse, | ||
| OrganicResult, | ||
| } from "../src/types.ts"; | ||
| import { getJson } from "../src/serpapi.ts"; |
There was a problem hiding this comment.
getJson is imported but I don't see it being used for any tests - could we remove if not needed
| device?: "desktop" | "tablet" | "mobile"; | ||
| no_cache?: boolean; | ||
| async?: boolean; | ||
|
|
There was a problem hiding this comment.
I'm wondering if we should extract out SerpApi Parameters and have the other engines' types extend it since nearly every other engine has the same SerpApi-specific params:https://serpapi.com/search-api#api-parameters-serpapi-parameters
What do you think @zyc9012
Summary
GoogleSearchParametersandGoogleSearchResponsetyped interfaces matching the Google Search API docsgetJson()— when you passengine: "google", you get autocomplete and typed responsesEngineParametersandBaseResponsepreserved for backwards compatibility with all other enginesOrganicResult,KnowledgeGraph,RelatedQuestion,SearchMetadata,SearchInformation, andSearchParametersContext
This is a starting point for addressing #33. The current types (
EngineParameters = Record<string, any>) provide no autocomplete, no typo protection, and no response typing. As the issue notes, this is effectively the same as not having TypeScript support.Typing every engine at once felt too large for a single PR. Instead, this PR is meant to be a pattern that can be incrementally applied to other engines.
Approach
Each engine gets its own file under
src/engines/. Adding Bing, YouTube, Amazon, etc. follows the same pattern: one file per engine, one typed overload per function.The index signature
[key: string]: unknownon the response type ensures new API fields work without SDK updates. This was a design decision that could be re-evaluated depending on desired maintenance burden for the SDK.